xlib.txt Copyright (c) 1995,96 xTech Ltd ---------------------------------------------------------------- XDS Library Manager ------------------- Libraries are files of a special format that are used to collect object modules or information required to tune import from DLL (so called "import libraries"). The XLIB.EXE utility included to this package is intended for library management. The following topics are discussed below: 1. Usage 1.1 Options 1.2 File Names 1.3 Response files 1.4 Commands 2. Operation modes 3. Proper librarian mode 4. Import Librarian Mode 5. Library Contents List Mode 6. Supported Formats 6.1. Output library format 6.2. Input object file format 6.3. Input executable format 6.4. Import Definition Files Format 1. Usage -------- To invoke XDS Library manager enter a command "xlib" with necessary arguments. Being invoked without additional arguments xlib outputs a brief help message similar to the following: XDS Library manager v1.0 (c) xTech 1995 usage = xlib /IMPLIB { option } libname[.lib] { file } | xlib { option } libname[.lib] { command } | xlib /LIST { option } libname[.lib] option = /OptionName[+|-|=ValueString] file = filename([.dll]|.exe|.idf) | @ResponceFileName command = { +|-|* }module[.obj] | @ResponceFileName "+" - add module to library "-" - remove module from library "*" - extract module to separate object file Options: /IMPLIB - create import library /LIST - show library contens /LOGO- - no logo /HELP - print this text /SAFE- - no "BAK" files /NEW - create new library file (without /LIST and /IMPLIB only) /PREFIX=str - set internal name prefix to "str" (with /IMPLIB only) /POSTFIX=str - set internal name postfix to "str" (with /IMPLIB only) An argument may be either an option, a file name, a command, or a response file. Arguments controls operation mode, name of output library and a set of files used to perform requested task. 1.1 Options Options may be placed in arbitrary order at the command line. Options are started with the slash ("/") character immediately followed by an option name and optionally with ON/OFF sign ("+"/"-") or with the "=" sign followed by a string value. In the first case the option is of BOOLEAN type while in the latter case it have a string value. Types of valid options are hard-coded in the program and improper type of an option would cause an error. If neither "+", "-", or "=" is present, the option is considered to be of BOOLEAN type with value "ON". Following is a list of all valid options with their meaning and default values. =============================================================== Name Type Default Effect value --------------------------------------------------------------- IMPLIB BOOL OFF Set xlib to "import librarian" mode of operation (See 4) LIST BOOL OFF If ON, xLib only outputs contents of a given library; no other operation is performed. (See 5) LOGO BOOL ON Specifies whether xLib has to print its logo. HELP BOOL OFF If ON, causes xLib to output a brief help text; no other operation is be performed. SAFE BOOL ON Sets the xlib to rename files to ".BAK" before overwriting them. NEW BOOL OFF xlib will always create a new library file instead of using the existing one. PREFIX Str empty Sets prefix of imported names (See 4). POSTFIX Str empty Sets postfix of imported names (See 4). =============================================================== If xlib encounters an unknown option, or an option that have no effect in a given operation mode, it produces a warning message. 1.2 File Names File names appearing in xlib's command line are regular file names. Each name may be prefixed with directory path. If extension is omitted defaults are used. Below is the list of default extensions for various types of files. Type Extension Library file .lib Object module .obj DLL .dll 1.3 Response files Response file for xlib is a text file that contains a number of xlib arguments, one per line. Any kind of argument is allowed except response file. Some options have no effect when used in response file, These are "IMPLIB", "LIST", "HELP" and "LOGO" options. 1.4 Commands Commands are names of files prefixed by a set of command signs. The signs are "+","-" and "*". Any other character used in a command prefix is interpreted as first character of a proper file name. Relational order of characters in the prefix have no meaning. Note that commands are valid for "library manager" operation mode only (See 3). 2. Operation modes ------------------ The xlib utility has three operation modes: library contents list mode, import librarian mode and proper librarian mode. Operation modes are switched by "IMPLIB" and "LIST" options as follows: i) If "IMPLIB" option is set, xlib is switched to import librarian mode (See 4). ii) If "LIST" option is set, xlib is switched to library contents list mode (See 5). iii) If both "IMPLIB" and "LIST" options are set, xlib is switched to import librarian mode (See 4). iv) If both "IMPLIB" and "LIST" modes are not set, xlib is switched to proper librarian mode (See 3). Details of operation modes are given in following chapters. 3. Proper librarian mode ------------------------ In this mode xlib acts as a proper library manager. First given argument that does not represent an option setting is treated as a name of a library file to deal with. If extension is omitted, the default ".lib" is added. If the option "NEW" is not set, the xlib supposes that the given library file should exist and should be valid, otherwise it produces a warning and createsa a new library file. Other arguments given in the command line or in a response file are treated as commands (see 1.4). Each command represents a set of actions and a name of object module or library. Valid actions are add, remove and extract. The are denoted by "+", "-" and "*" characters respectively. When more than one action is specified, xlib performs them in following order: 1) extract 2) remove 3) add For instance, to replace module "a.obj" you may use either "-+a" or "+-a". If all commands are successfully executed, xlib checks the resulting library for duplicate names, producing warnings if necessary. Then xlib creates an output library file and writes the resulting library. If any file with name equal to output file name does already exist then xlib may save it by changing its extension to ".BAK" before overwrite. It is controlled by the SAFE option that is set ON by default. 4. Import Librarian Mode ------------------------ In this mode xlib produces special kind of library - so called "import library". This kind of libraries contain the information for a linker on how to tune up import information in the target executable. Import libraries are commonly used instead of definition files. To switch xlib to import librarian mode set the "IMPLIB" option ON (i.e. use "/IMPLIB" or "/IMPLIB+" string in the command line). In this mode xlib treats first given argument that does not represent an option setting as a name of an output library file. If extension is omitted, default ".lib" is added. xlib always creates new file for the resulting library. If a file with a given name does already exist, xlib may save it by changing its extension to ".BAK" depending on "SAFE" option setting. Other arguments that do not represent option settings are treated as names of source files. xlib may retrieve information required to create an import library from two kinds of sources, namely from an executable (EXE of DLL) or from a special script file (Import Definition File). The type of source is determined by its extension, where ".exe" stands for executable, ".dll" stands for dynamically linked library and ".idf" stands for import definition file. If extension is omitted, ".dll" is added by default. See 6 for details of supported formats. In general, an import library sets correspondence between an internal name (e.g. name that may be referenced from a program) to a DLL name and an exported entry within it. Internal names should be properly mangled to fit naming convention of a programing system. xlib provides a simple mechanism for names mangling when it is necessary. It uses value of the "PREFIX" option as a prefix and value of the "POSTFIX" option as a postfix for all internal names it produces. For example, being invoked with /PREFIX=_IMP_ /POSTFIX=_EXP_ xlib will mangle entry "OneEntry" to name "_IMP_OneEntry_EXP_". 5. Library Contents List Mode ----------------------------- In this mode xlib outputs listing of a library contents. To switch xlib to library contents mode set "LIST" option ON (i.e. add "/LIST" or "/LIST+" to the command line). In this mode xlib treats first given argument as a library file name. If extension is omitted, the default ".lib" is added. A file should exist and should be a correct library file, otherwise xlib produces an error report. Other arguments that are not option settings are ignored. Library contents is printed as follows: XDS Library manager v1.0 (c) xTech 1995 Library "libxds.lib" MODULE src\xr\xrMM.mod xrMM_Align xrMM_COLLECTOR xrMM_DoDefrag xrMM_DynarrDescSize xrMM_free_block xrMM_ini_type_desc xrMM_parts xrMM_BEGIN MODULE src\xr\xrO2MM.mod X2C_DESTRUCTOR X2C_DISPOSE X2C_GET_TD X2C_MODULE X2C_NEW X2C_NEW_OPEN xrO2MM_BEGIN 6. Supported Formats -------------------- Here input and output formats currently supported by xlib are discussed. 6.1. Output library format Currently xlib produces output libraries in OMF format only. This format is compatible with most of current linkers. The important exception is link386 by Microsoft that expects libraries in COFF format. COFF format will be supported later. 6.2. Input object file format Currently xlib expects all input object files to be in OMF format. Most modern compilers, including XDS compilers, produce object files in this format. The important exception are MSVC (v2.0 and higher) compilers by Microsoft which produce output in COFF format. COFF format will be supported later. 6.3. Input executable format The xlib may retrieve export information for import libraries from executables (either DLL or EXE) which are in "PE" (Portable Executable) format only. This format is used for all 32-bit executables in Windows95 and WindowsNT. Other executable formats will be supported later. 6.4. Import Definition Files Format Below is the description of the import definition files format. The description is given in the Extended Backus-Naur Formalism. Brackets "[" and "]" denotes optionality of the enclosed expression, braces "{" and "}" denotes repetition possibly 0 times. Terminal symbols are given in capitals (e.g. FROM) or are enclosed within quotation marks (e.g. ";"). File = OneImport ";" { OneImport ";" } . OneImport = FROM DllName IMPORT Entry { "," Entry } . Entry = ExportedEntryName [ AS InternalName ] . DllName = name of the DLL or EXE ExportedEntryName = name of exported entry . InternalName = internal name for the entry . Lines starting with "%" are considered to be comments and ignored. Note that if InternalName is omitted, the ExportedEntryName is used as internal name. Example of import definition file: % Copyright (c) 1996 xTech Ltd., Russia % % Sample Import Definition File % FROM KERNEL32.DLL IMPORT CreateFileA ,WriteFile ,ReadFile ,DeleteFileA ,MoveFileA ,SetFilePointer ,SetSystemTime ,RtlFillMemory AS FillMemory ; FROM USER32.DLL IMPORT ShowWindow ,ShowWindowAsync ,TileWindows ; % end of the sample import definition file [end of document]